home *** CD-ROM | disk | FTP | other *** search
/ Whiteline: delta / whiteline CD Series - delta.iso / tools / falc_uti / xbragger / xgrabber.doc < prev    next >
Text File  |  1995-11-25  |  14KB  |  276 lines
  1. ##############################################################################
  2.                       XGrabber Version 0.24 (The Silicon Version)
  3.                                    ~ Dokumentation ~
  4. ##############################################################################
  5.  
  6. (c) 1994 Inter development / The Independent
  7. Geschrieben von Christian Pick (Lucky of ST)
  8.                 Rheinbrückenstraße 5
  9.                 76187 Karlsruhe
  10.                 0721 / 562776
  11.  
  12.  
  13. Dokumentation für Rainer Lissowski. (Thanx!)
  14. GFX-Konverter für Kay Tennemann (Agent T / Cream)
  15. Silicon Version für alle Franzosen, die glaubten ihre Demos seien sicher :-)
  16. (Ja - ich weiß! "Agony" ist immer noch 'ne verdammte Nuß...)
  17.  
  18.  
  19.  
  20. Vorab: Der XGrabber ist kein fertiges Produkt und wird nur bei Bedarf und auf 
  21. Anfragen hin weiterentwickelt. Er ist keineswegs fehlerfrei, erfüllt aber 
  22. seinen Zweck bei richtiger Anwendung.
  23.  
  24.  
  25.  
  26.                                  Die Dateien
  27.                                 ~~~~~~~~~~~~~
  28.  
  29. F_REGS.S        Falcon-Registerbeschreibung von bITmASTER (BSW)
  30. GFX->###.*      Konvertierroutine von GFX nach RAW oder TPI (Automatische 
  31.                 Erkennung)
  32. GFX->PI#.*      Konvertierroutine von GFX nach PI? (Degas); ST-Kompatibel
  33. GFX->RAW.*      Konvertierroutine von GFX nach RAW
  34. GFX->TPI.*      Konvertierroutine von GFX nach TPI
  35. GRABSHOW.SRC    Sourcecode von XGS_ST.TTP und XGS_F030.TTP
  36. XGRABBER.*      Das Hauptprogramm mit Sourcen und Dokumentation
  37. XGRAB_J.*       Programm & Source für Jaguar-Pad:
  38.                   Alle neuen Versionen sind für das Jaguar-Pad! Alle 
  39.                   neueren Features sind nur hier vorhanden!
  40.  
  41.  
  42.  
  43.                                   Anwendung
  44.                                  ~~~~~~~~~~~~
  45.  
  46. Der Xgrabber funktioniert (hoffentlich) auf jedem Falcon 030-System. Er ist 
  47. auf den 68030er und 68040er-Prozessoren zugeschnitten und kann auch nur auf 
  48. diesen Typen (eventuell auch höher...) betrieben werden. Auf anderen Systemen 
  49. wird es zu Abstürzen kommen, da keine Sicherheitsabfragen vorgenommen werden!
  50. Zur Bedienung des XGrabbers wird ein Joystick oder ein Jaguar-Pad für den 
  51. STE-Joystickport A benötigt. Die Belegung für ein Adapterkabel (für 
  52. Joysticks...) steht weiter unten. Da der XGrabber mit Sourcecode (Turbo-
  53. Assembler und GFA-Basic) vorliegt kann man ihn auch nach Belieben selber 
  54. erweitern und ändern. So ist auch eine Steuerung über andere Ports 
  55. möglich. Ich habe mich für den STE-Port entschieden, da hier die 
  56. Joystickdaten keinen Interrupt auslösen und so ein unproblematisches 
  57. Auslesen dieser Daten möglich ist.
  58. Um den XGrabber benutzen zu können, muß man ihn nur einmal nach jedem Reset 
  59. oder Warmstart laden. Er ist nun resident im Speicher (und überlebt auch 
  60. einen Wechsel der Auflösung). Aktiviert wird er über einen Druck auf den 
  61. Feuerknopf des Joysticks 0 im STE-Joystickport A. Nach Loslassen des 
  62. Knopfes wird das aktuelle Bild mit Auflösungs- und Farbinformationen 
  63. gespeichert. Es handelt sich um ein eigenes Format, Erklärung weiter unten.
  64. Über den Vergleich der aktuellen Registerwerte mit den Werten für 
  65. ST-Kompatibilitätsauflösungen versucht der XGrabber auch herauszufinden, ob 
  66. man sich in einem ST-Modus befindet. Bisher hat dies funktionert, aber 
  67. theoretisch kann dies auch zu Fehlern führen. Mir ist leider keine bessere 
  68. (und einfachere) Möglichkeit bekannt. Sollte man in einer ST-Auflösung sein, 
  69. so wird das Bild nicht im Grabber-Format (GFX), sondern im PI?-Format 
  70. gespeichert. PI1-Bilder können von Neochrome, PI2- und PI3-Bilder von Degas 
  71. Elite geladen werden.
  72. Die neuen XGrabber-Versionen werden über ein Jaguar-Pad gesteuert. Durch 
  73. Druck auf einen Feuerknopf kann man das aktuelle Bild speichern. Da 
  74. einige Demos inzwischen versuchen sich gegen den XGrabber zu schützen 
  75. gibt es ab sofort eine neue Version: Durch Druck auf den Pause-Knopf kann 
  76. man den Tracer aktivieren. Solange man Pause drückt, wird jeder Befehl 
  77. des aktiven Programmes während der Laufzeit untersucht und - falls er das 
  78. VBR-Register manipuliert oder abfragt - entsprechend behandelt. So kann man 
  79. z.B. auch in das Demo "Agony" eindringen. Beim Starten und beim wechseln 
  80. zwischen den Effekten muß man nur Pause drücken und schon bleibt der 
  81. XGrabber aktiv... Etwas umständlich ist das zwar schon, aber wenigstens 
  82. kann man in die Programme eindringen. Das Tracen ist natürlich extrem 
  83. langsam. Man sollte daher nur an benötigten Stellen Pause drücken. Durch 
  84. einen neuen Handler konnte auch die Transparenz des XGrabber zu den DSP-
  85. Playroutinen erhöht werden. Knackser und Musik-Abstürze (teilweise daraus 
  86. folgende Programmabstürze...) konnten so verringert werden.
  87.  
  88.  
  89.                           Die Dateinamen und der Pfad
  90.                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  91.  
  92. Da sich der XGrabber in laufenden Programmen aktiert fragt er nicht jedesmal 
  93. nach einen Dateinamen. Stattdessen vergibt er automatisch die Kennung 
  94. "GRAB???.GFX" (bzw. "GRAB???.PI?"). Die drei Fragezeichen sind dabei die 
  95. jeweilige Nummer des Bildes. Die Zählung beginnt bei "000" und nach jedem 
  96. Start des XGrabbers neu! Der XGrabber überprüft, ob ein Bild 
  97. gleichen Namens bereits vorhanden ist. Er benutzt dann immer den 
  98. ersten freien Eintrag, dessen Nummer höher als die zuletzt 
  99. vergebene ist.
  100. Der Zielpfad kann nur direkt im Listing eingestellt werden. Voreingestellt 
  101. ist das Rootdirectory von Laufwerk C, also "C:\".
  102. WICHTIG: Auf dem entsprechenden Laufwerk muß genügend Platz sein! Dies wird 
  103. der Einfachheit halber nicht überprüft. Bei neueren AHDI-Treibern führt 
  104. Platzmangel zu keinen Fehlern, bei alten (wie die ersten für den Falcon...) 
  105. wird gnadenlos die folgende Festplattenpartition beschrieben. Leider steht zu 
  106. Beginn der Partition die FAT und so gehen ALLE Daten der Partition kaputt!!! 
  107. Also unbedingt für genügend freien Platz sorgen!
  108.  
  109.  
  110.                             Anzeigen von Bildern
  111.                            ~~~~~~~~~~~~~~~~~~~~~~
  112.  
  113. Zum Anzeigen der gespeicherten Bilder sind die beiden Programme "XGS_ST.TTP" 
  114. und "XGS_F030.TTP" vorhanden. Die einfachste Möglichkeit ist einfach das 
  115. gewünschte *.GFX-Bild auf das TTP-Programm zu ziehen. ACHTUNG: Bilder in der 
  116. jeweils falschen Auflösung führen zu einem Absturz!
  117. Beide Anzeige-Programme sind mit dem Source "GRABSHOW.SRC" erzeugt worden. 
  118. Hier kann man auch die Verwendung eines XGrabber-Bildes sehen.
  119.  
  120.  
  121.                           Fehler (Unbedingt lesen!!!)
  122.                          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  123.  
  124. Hierbei handelt es sich nicht unbedingt um Fehler, aber auf einige Sachen muß 
  125. man beim Arbeiten mit dem XGrabber unbedingt achten.
  126. Leider verträgt sich der XGrabber nicht mit allen Programmen. Da er sehr 
  127. tiefe Eingriffe in deren Ablauf vornimmt, ist dies auch kaum zu erwarten. 
  128. Nach oder während dem Speichern eines Bildes kann es so zum Absturz kommen. 
  129. Grund hierfür sind meistens Interrupts oder das TOS, wenn es gerade aktiv 
  130. war. Hiergegen kann man leider nichts machen, da einige Programme wegen den 
  131. Interrupts abstürzen und andere, wenn die Interrupts fehlen. Die momentane 
  132. Lösung ist meiner Meinung nach die beste. Vielleicht finde ich ja irgendwann 
  133. noch eine bessere.
  134.  
  135.  
  136.                          Aufbau des Adapterkabels
  137.                         ~~~~~~~~~~~~~~~~~~~~~~~~~~
  138.  
  139. Material: 1 SUB-D Stiftleiste, 15-Polig (3-Reihig) [Anschluß STE-Port]
  140.           1 SUB-D Stiftleiste,  9-Polig (2-Reihig) [Jostickanschluß]
  141.           6 Drähte (jeweils etwa 3-4 cm)
  142.  
  143. Das Adapterkabel ist ein ganz normaler Anschluß für einen Joystick an den 
  144. STE-Port. Im Grunde genügt der Anschluß des Feuerknopf-Kabels (wozu dann auch 
  145. nicht unbedingt die 15-polige Stiftleiste nötig ist, da man einen einzelnen 
  146. Draht auch gut einfach in die Buchste stecken kann...), aber so kann man 
  147. besser mehr Funktionen in den XGrabber einbauen.
  148.  
  149. Die Verdrahtung ist simpel. Es müssen nur jeweils die Pins 1, 2, 3, 4 und 6 
  150. der beiden Stiftleisten miteinander verbunden werden. Der sechste draht 
  151. geht von Pin 8 (9-Polige Stiftleiste) auf Pin 9 (15-Polige Stiftleiste) Das 
  152. war's dann auch schon.
  153.  
  154.  
  155.                          Dateiformat vom XGrabber
  156.                         ~~~~~~~~~~~~~~~~~~~~~~~~~~
  157.  
  158. Die Kürzel .b, .w und .l entsprechen der Assembler-Syntax und stehen für 1, 2 
  159. und 4 Bytes Datenlänge.
  160.  
  161.  
  162. Grober Aufbau:
  163.    38 Bytes Auflösungsinformationen
  164.  1024 Bytes Farbinformationen 256-Farben Falcon-Palette
  165.    32 Bytes Farbinformationen 16-Farben STE-Palette
  166.     ? Bytes Bildinformationen
  167.  
  168. Die Auflösungsinformationen:
  169.  
  170. Länge | Hardwareadresse | Beschreibung
  171. ------|-----------------|-------------------------------
  172.   .w  | $FFFF8260.w     | ST-Shift-Mode
  173.   .w  | $FFFF8266.w     | Falcon-Shift-Mode
  174.   .w  | $FFFF8282.w     | Horizontal Hold-Timer
  175.   .w  | $FFFF8284.w     | Horizontal Border-Begin
  176.   .w  | $FFFF8286.w     | Horizontal Border-End
  177.   .w  | $FFFF8288.w     | Horizontal Display-Begin
  178.   .w  | $FFFF828A.w     | Horizontal Display-End
  179.   .w  | $FFFF828C.w     | Horizontal Sync-Start
  180.   .w  | $FFFF82A2.w     | Vertical Frequenz-Timer
  181.   .w  | $FFFF82A4.w     | Vertical Border-Begin
  182.   .w  | $FFFF82A6.w     | Vertical Border-End
  183.   .w  | $FFFF82A8.w     | Vertical Display-Begin  (VDB)
  184.   .w  | $FFFF82AA.w     | Vertical Display-End    (VDE)
  185.   .w  | $FFFF82AC.w     | Vertical Sync-Start
  186.   .w  | $FFFF82C0.w     | Video Control
  187.   .w  | $FFFF82C2.w     | Video Mode
  188.   .w  | $FFFF820E.w     | Line Offset
  189.   .w  | $FFFF8210.w     | Line-Wide
  190.   .w  | $FFFF8264.w     | H-Scroll
  191.  
  192. Aus diesen Daten kann man alle benötigten Daten über das Bild berechnen. 
  193.  
  194.  
  195.                                  Internes
  196.                                 ~~~~~~~~~~
  197.  
  198. Der XGrabber wird nur durch das "Vector Base Register" (VBR) ermöglicht. 
  199. Dieses Register gibt an, wo im Speicher die Basis zu den Exception-Vektoren 
  200. liegt. Bei den Atari-Rechnern ist dies Standardmäßig bei Null und alle 
  201. bekannten Programme behandeln dies als eine unbedingte Tatsache. Dies ist es 
  202. aber nicht und so kann sich der XGrabber, für andere Programm vollkommen 
  203. transparent, in andere Programme einklinken. Die normalen Exception-Vektoren 
  204. werden überhaupt nicht berührt! Statt dessen verbiegt der XGrabber alle 
  205. Vektoren mittels VBR auf seine eigene Tabelle, in der nur Routinen stehen, 
  206. die sofort zu den normalen Exception-Routine springen. Mit einer Ausnahme: 
  207. Der VSync-Interrupt. Bei diesem wird noch abgefragt, ob der Joystickknopf 
  208. betätigt wird. Wenn nicht, arbeitet das Programm normal weiter, wenn ja wird 
  209. der XGrabber aktiviert.
  210. Eine recht einfache Arbeitsweise, die sich dank seiner Transparenz auch mit 
  211. fast allen Programmen verträgt. Leider läßt sich der XGrabber genauso leicht 
  212. auch aus seinen eigenen Programm heraus entfernen. Man muß hierzu einfach zu 
  213. Programmstart (im Supervisor-Modus!) das VBR-Register auf Null oder auf eine 
  214. eigene Tabelle setzen. Sofort hat der XGrabber nichts mehr zu melden und ist 
  215. eine erstklassige Speicherleiche...
  216. Nachtrag: In den neuen XGrabber-Versionen kann mittels des Trace-Modus 
  217. auch alle VBR-Manipulationen und -Abfragen abgefangen werden. Der 
  218. XGrabber ist dann vollkommen transparent! Störend kann jetzt nur noch der 
  219. Trace-Modus sein. (Durch die Zeitverzögerung kann es erhebliche Probleme 
  220. geben...) Wie man den XGrabber dennoch sauber (!) ausschaltet, wird hier 
  221. nicht verraten...
  222.  
  223.  
  224.                       Formatkonvertierung GFX -> TPI
  225.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  226.  
  227. Leider liegen mir keine Informationen zu verschiedenen Grafikformaten vor. 
  228. Deshalb konnte ich auch keine komplexen Konvertierer schreiben. Ein einfaches 
  229. Format ist TPI (TruePaint Image). In dieses TrueColor-Grafikformat lassen 
  230. sich nur TrueColor-Bilder konvertieren. Diese können dann mit Hilfe von 
  231. TruePaint in andere gängige Formate konvertiert werden.
  232.  
  233.  
  234.                       Formatkonvertierung GFX -> RAW
  235.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  236.  
  237. Dieser Konverter konvertiert 256-Farben-GFX-Bilder in das 24-Bit-RAW-Format. 
  238. Das RAW-Format kann ebenfalls mit TruePaint in andere Formate konvertiert 
  239. werden.
  240. Da der Sourcecode aller Konvertierer beiliegt, kann man ihn relativ leicht 
  241. auch an andere Plane-Modies anpassen.
  242.  
  243.  
  244.                       Formatkonvertierung GFX -> PI?
  245.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  246.  
  247. Eigentlich sollte der XGrabber ST-Kompatibilitätsauflösungen anhand seiner 
  248. Vergleiche erkennen. Trotzdem kommt es oft vor, daß er dies nicht schafft. In 
  249. diesem Fall speichert er das Bild ebenfalls als GFX-Bild ab, daß man sich mit 
  250. "XGS_ST.TTP" ansehen kann. Um es trotzdem in das PI?-Format zu bringen kann 
  251. man diesen Konvertierer benutzen.
  252.  
  253.  
  254.                       Formatkonvertierung GFX -> ###
  255.                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  256.  
  257. Nein! "###" ist kein neues Format. Dies ist nur die Zusammenfassung aus dem 
  258. RAW- und TPI-Konverter. Im Allgemeinen sollte man dieses Konvertierprogramm 
  259. verwenden. Es erkennt automatisch, ob es sich um ein TrueColor- oder 
  260. 256-Farben-Bild handelt und konvertiert es in das entsprechende Format. 
  261. Anschließend hat man noch die Möglichkeit, das GFX-Bild vom Programm löschen 
  262. zu lassen.
  263.  
  264.  
  265.  
  266.  
  267.  
  268. Wer noch Anregungen, neue Konvertierroutinen, Informationen über verschiedene 
  269. Grafikformate oder sonstige Probleme hat, soll mir alles in einen Brief 
  270. packen und schicken. Rückporto wäre auch nicht schlecht.
  271.  
  272.                 Lucky of ST
  273.  
  274.  
  275.  
  276.